home *** CD-ROM | disk | FTP | other *** search
/ Super PC 34 / Super PC 34 (Shareware).iso / spc / UTIL / DJGPP2 / CONTRIB / MAN_PC.ZIP / man_pc / README.all
Encoding:
Text File  |  1995-06-20  |  6.3 KB  |  161 lines
  1. README (man, whatis, 95/06/18)
  2. ------------------------------
  3.  
  4. someone (stanb@netcom.com) had asked for a man(1) command for reading
  5. manpages. i am posting such a system which includes:
  6.  
  7. man - read online manpages
  8. apropos - list relevant manpages on a given topic (same as "man -k word")
  9. whatis - give 1-line description of a command (same as "man -f word")
  10. whatisin - list information about what is in sections of the manual
  11. mkwhatis - tool to help build whatis database
  12.  
  13. note that man does not have its own pager. man calls the pager and
  14. gives it a filename. what man does is find the file (in known places)
  15. and figures out what to run (pager, whatis, apropos, etc.). in this
  16. regard it is really pretty simple minded. the hard part is getting,
  17. organizing, formatting, and maintaining the manpages. for example, i
  18. have hundreds of manpages on my systems. the typical unix system might
  19. have over a thousand manpages.
  20.  
  21. these programs function more or less the same as the unix (BSD) commands
  22. with some exceptions:
  23.  
  24.     - man does not invoke nroff. your manpages should be preformatted.
  25.     - every unix flavor has its own way of doing man so some of the
  26.       switches on these commands may not correspond with all unix
  27.       (or posix) ways of dealing with this.
  28.     - the whatis database itself is different than how unix does it.
  29.       but it is similar, and no two unix systems do it the same
  30.       anyway.
  31.  
  32. as it stands, these programs assumes the following directory structure:
  33.  
  34.     c:\usr\man        main location of manpages, whatis db, etc
  35.     c:\usr\man\man[0-9lno]    dirs containing *unformatted* manpages)
  36.     c:\usr\man\cat[0-9lno]    dirs containing *formatted* manpages)
  37.     c:\usr\man\whatis._?_    whatis databases for each section (you
  38.                 have to build these based on your collection
  39.                 of manpages)
  40.     c:\usr\man\whatisin.___    whatisin database
  41.  
  42. man will ONLY look in the cat* directories, and does not format the manpages.
  43. you will need nroff for this (cawf, groff, etc). i also have an nroff
  44. that i wrote years ago that is PD. or you can format the manpages on a unix
  45. system and download them to your PC.
  46.  
  47. everything is configurable, both in the source and via the environment.
  48. for example, the c:\usr\man path can be overridded with:
  49.  
  50.     - setting environment variable MANPATH
  51.     - using the commandline switch "-M path" on each command
  52.     - changing the executables with a binary editor (i have left
  53.       space in the source for such patches)
  54.     - changing the source and recompiling
  55.  
  56. caveats:
  57.  
  58.     - i am providing this free, with no restrictions. it is 100% my
  59.       code (does not contain any unix code).
  60.     - i will not help in any way to fix anything or add new features.
  61.       this system runs fine under both Unix and on my atari ST (with
  62.       gcc) so it should port easily, though i have not tried it under
  63.       DOS or with djgpp.
  64.     - i will not reformat the source to correspond to someone's notion
  65.       of style. this is my prefered style, after 10 years of C coding
  66.       and 20 years of fortran coding. :-)
  67.     - if you don't like it, either a) fix it yourself, or b) don't use
  68.       it. it is free, after all.
  69.  
  70. Install:
  71.  
  72.     - Unpack everything into separate directories (./man, ./whatis).
  73.     - The files are all ascii (no binary files). there are no CF-LF
  74.       (just LF) so if you need CR-LF, you have to fix this yourself.
  75.     - go to each dir (./man and ./whatis) and look at the makefile.
  76.       change (at least) the following for your particular setup:
  77.  
  78.         CC        how to invoke compiler
  79.         LD        how to link .o files
  80.         MANTOP        main location to place manpages (install)
  81.         MANDIR        specific location for manpage source
  82.         CATDIR        specific location for formatted manpages
  83.         BINDIR        location to install executables (man,
  84.                 whatis, etc)
  85.         DEFS        in man, you should specify what you have
  86.                 available (eg, if you have ul(1) and want
  87.                 the -ul switch to function, define HAS_UL).
  88.                 you probably want to define MSDOS, __GNUC__,
  89.                 and possibly undefine unix.
  90.  
  91.         in general, check all the macros in upper case in the
  92.         makefile. note that i could have used sed in the makefile
  93.         to patch names in the program, but i don't know how good
  94.         make is on the PC.
  95.  
  96.     - man invokes the PAGER and other programs via the system(3) call.
  97.       on unix (and on my atari), system will search PATH for executables
  98.       so you don't need a full path. if this is not the case with djgpp,
  99.       then you will have to alter ./man/man.c to build a full path
  100.       for executing PAGER, cat, ul, whatis, apropos, etc.
  101.  
  102.     - type:
  103.  
  104.         make all        will build the executables
  105.         make install        will install the execs and manpages
  106.         make clobber        will clean up after the make all.
  107.  
  108.       you may also consider doing "make dirs" before make install
  109.       when building man. this creates the directory structure.
  110.  
  111.       you should do man before whatis.
  112.  
  113.     - if successful, you should be all set. i have provided formatted
  114.       manpages (man.1, whatis.1, whatis.5, apropos.1, whatisin.1) from
  115.       the manpage sources (man.man, whatis.man, whatis.ma5, etc). these
  116.       were piped through "ul -t dumb" to remove any bold/underline
  117.       escape sequences. so the formatted manpages are pure ascii. if
  118.       you have a PAGER that groks how to handle nroff bold, etc, then
  119.       you may want to reformat the manpages.
  120.  
  121. you should at a minimum build man. it will allow you to read manpages.
  122. if you are up for it, the whatis capability might be desirable. whatis
  123. contains a 1-line description of every manpage you have on your system.
  124. for more information, see the file ./whatis/whatis.5 and whatis.1.
  125.  
  126. note: i have not included any manpages here other than those for these
  127. programs themselves. don't ask me for a manpage on ls(1).
  128.  
  129.  
  130.  
  131. Environment:
  132.  
  133. these programs recognize several environment variables:
  134.  
  135.     MANPAGER    man    if set, this pager is used by man. on my
  136.                 atari, i have a special pager that resets
  137.                 fonts, based on what -T does in nroff on
  138.                 my system. this gives me bold, etc.
  139.     PAGER        man    if MANPAGER is not set, this pager is used.
  140.                 the default is less.
  141.     MANPATH        man,    location of the manpages, top level. the
  142.             whatis    default is c:\usr\man. at the moment, MANPATH
  143.             apropos    is a single path, not a list.
  144.             whatisin
  145.  
  146. for more, grep the sources for "getenv" or read the manpages.
  147.  
  148. note that man will invoke other programs as follows (using system(3)):
  149.  
  150.     man file    PAGER
  151.     man -k word    apropos
  152.     man -f name    whatis
  153.  
  154. you can also invoke apropos and whatis by themselves, of course.
  155.  
  156. that's about all i have time for. have fun...
  157.  
  158. -bill rosenkranz
  159. rosenkra@convex.com
  160.  
  161.